Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions That Modify Movie Properties / Working With Data References

GetMediaDataRef

The GetMediaDataRef function returns a copy of a specified data reference. Your application identifies the data reference with the appropriate data reference index.

pascal OSErr GetMediaDataRef (Media theMedia, short index, 
                              Handle *dataRef, 
                              OSType *dataRefType, 
                              long *dataRefattributes);

theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on page 2-138 and page 2-190, respectively).

index

Identifies the data reference. You provide the index value that corresponds to the data reference. It must be less than or equal to the value that is returned by the GetMediaDataRefCount function, described in the previous section.

dataRef

Contains a pointer to a field that is to receive a handle to the data reference. The media handler returns a handle to information that identifies the file that contains this media's data. The type of information stored in that handle depends upon the value of the dataRefType parameter. If the function cannot locate the specified data reference, the handler sets this returned value to nil. Set the dataRef parameter to nil if you are not interested in this information.

dataRefType

Contains a pointer to a field that is to receive the type of data reference. If the data reference is an alias, the media handler sets this value to 'alis', indicating that the reference is an alias. Set the dataRefType parameter to nil if you are not interested in this information.

dataRefattributes

Contains a pointer to a field that is to receive the reference's attribute flags. The following flags are available (unused flags are set to 0):

dataRefSelfReference

Indicates whether the data reference refers to the movie resource's data file. If this flag is set to 1, the data reference identifies media data that is stored in the same file as the movie resource.

dataRefWasNotResolved

Indicates whether the Movie Toolbox resolved the data reference. If this flag is set to 1, the Movie Toolbox could not resolve the data reference. For example, the toolbox may be unable to resolve data references because the required storage device is unavailable at the time a movie is loaded. If the data reference is unresolved, the Movie Toolbox disables the corresponding track.

Set the dataRefAttributes parameter to nil if you are not interested in this information.

DESCRIPTION

You can use GetMediaDataRef function to retrieve information about a data reference. For example, you might want to verify the condition of a movie's data references after loading the movie from its movie file. You could use this function to check each data reference.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

SEE ALSO

You can add a data reference to a media by calling the AddMediaDataRef function, which is described on page 2-200. You must dispose of a media's data references yourself by disposing of its handle. You can determine the number of data references in a media by calling the GetMediaDataRefCount function, which is described in the previous section.